/**
 * This file is part of 1genia trampoline
 * Copyright (C) 2007-2008 1genia (contact@1genia.com)
 *
 * This library is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; version 3 of the License. 
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details. 
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; see the file COPYING.TXT.  If not,
 * write to the Free Software Foundation, Inc., 51 Franklin Street,
 * Fifth Floor, Boston, MA 02110-1301, USA. 
 **/
package com.genia.toolbox.spring.transaction.bean;

import org.springframework.transaction.TransactionDefinition;
import org.springframework.transaction.TransactionStatus;

import com.genia.toolbox.basics.exception.technical.TechnicalException;

/**
 * marker interface for resource that want to be enlisted in the
 * EnlistablePlatformTransactionManager.
 */
public interface EnlistableResource
{

  /**
   * commit the transaction defined by {@link TransactionStatus}. A
   * {@link #prepare(TransactionStatus)} must have been called.
   * 
   * @param status
   *          the {@link TransactionStatus} of the transaction
   * @throws TechnicalException
   *           if an error occured
   */
  public abstract void commit(TransactionStatus status)
      throws TechnicalException;



  /**
   * prepare the transaction defined by {@link TransactionStatus}. If this
   * method succeed, a {@link #commit(TransactionStatus)} must succeed or the
   * transactional integrity of the application won't be insured.
   * 
   * @param status
   *          the {@link TransactionStatus} of the transaction
   * @throws TechnicalException
   *           if an error occured
   */
  public abstract void prepare(TransactionStatus status)
      throws TechnicalException;



  /**
   * rollback the transaction defined by {@link TransactionStatus}.
   * 
   * @param status
   *          the {@link TransactionStatus} of the transaction
   * @throws TechnicalException
   *           if an error occured
   */
  public abstract void rollback(TransactionStatus status)
      throws TechnicalException;



  /**
   * start a new transaction for the current object.
   * 
   * @param definition
   *          {@link TransactionDefinition} instance (can be <code>null</code>
   *          for defaults), describing propagation behavior, isolation level,
   *          timeout etc
   * @param status
   *          the {@link TransactionStatus} of the transaction
   * @throws TechnicalException
   *           if an error occured
   */
  public abstract void startTransaction(TransactionDefinition definition, TransactionStatus status)
      throws TechnicalException;
}
